Skip to main content

Dockerfile Documents in detail

Docker can automatically build an image by reading the commands in the Dockerfile. A Dockerfile is a text document that contains all the commands and instructions for the user to create an image.

I. Variables​

Variables are represented by $variable_name or ${variable_name}

  • ${variable:-word} means that if variable is set, the result will be that value. If variable is not set, word will be the result.
  • ${variable:+word} means that if variable is set then word will be the result, otherwise it will be the empty string.

Variables preceded by \ can be escaped to a normal string: \$foo or \${foo}``, indicating conversion to $fooand${foo}` text strings.

II. FROM​

Initialize a new build phase and set up the base image：

FROM [--platform=<platform>] <image> [AS <name>]
FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]
FROM [--platform=<platform>] <image>[@<digest>] [AS <name>]
  • A single dockfile may have multiple occurrences of FROM, to use a previous build phase as a dependency for another build phase.
  • AS name indicates a name for the build stage, which can be used in subsequent FROM and COPY --from=<name> instructions to reference the image built at this stage.
  • digest is actually an ID based on the contents of the image, and will not change as long as the contents of the image remain the same digest.
  • The tag or digest value is optional. If you omit either one, the builder defaults to a latest tag. If this tag value is not found, the builder will return an error.
  • The --platform flag can be used to specify a platform in the case of a FROM reference to a multi-platform image. For example: linux/amd64, linux/arm64, or windows/amd64

三、RUN​

will execute the command in a new layer on top of the current image, to be run at docker build time.

RUN /bin/bash -c 'source $HOME/.bashrc; \
echo $HOME'

RUN There are two forms.

  • RUN <command> (shell form where the command is run in a shell, default /bin/sh -c on Linux or cmd /S /C Windows).
  • RUN ["executable", "param1", "param2"] (executable form)

Description.

  • A single RUN instruction can be continued to the next line using \ (backslash).
  • The instruction cache is not automatically invalidated during the next build of RUN. The instruction cache can be invalidated using the -no-cache flag.
  • Each execution of a Dockerfile directive creates a new layer on top of the docker. So too many meaningless layers will cause the image to bloat too much. You can use the && symbolic concatenation command, which will only create 1 layer of images when executed.

四、CMD​

Run the program when docker runs, but unlike the run command, RUN is run when docker builds.

FROM ubuntu
CMD ["/usr/bin/wc","--help"]

Three formats are supported.

  • CMD ["executable", "param1", "param2"] Executed using exec, the recommended way.
  • CMD command param1 param2 is executed in /bin/sh and is provided to applications that require interaction.
  • CMD ["param1", "param2"] Default arguments provided to ENTRYPOINT.

Specifies the command to be executed when starting the container; each Dockerfile can only have one CMD command. If multiple commands are specified, only the last one will be executed.

If the user specifies a command to run when starting the container, the command specified by CMD will be overwritten.

V. LABEL​

Adding metadata.

LABEL multi.label1="value1" \
      multi.label2="value2" \
      other="value3"

六、EXPOSE​

EXPOSE <port> [<port>/<protocol>...]

The Docker container listens on the specified network port at runtime. You can specify whether the port is listening on TCP or UDP; if you don't specify a protocol, the default is TCP.

The EXPOSE command does not actually publish the port. To actually publish a port when running the container, docker run -P to publish and map one or more ports.

By default, EXPOSE assumes TCP, and you can also specify UDP.

EXPOSE 80/udp

七、ENV​

Set environment variables.

ENV <key>=<value> ...

The environment variables set will persist and you can view them using docker inspect. Use docker run --env <key>=<value> to change the value of the environment variable.

If the environment variable is only needed during the build, consider setting a value for a single command.

RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ...

Or use ARG, which will not remain in the final image.

ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y ...

八、ADD​

Copies new file, directory or remote file URLs <src> and adds them to <dest>.

<src> may specify multiple resources, but if they are files or directories, their paths are interpreted as relative to the source of the build context, which is WORKDIR.

Each all <src> may contain wildcards, and the match will use Go's filepath.Match rule. For example, to add all files starting with "hom".

ADD hom* /mydir/

In the following example, ? is replaced with any single character, e.g. `home.txt'.

ADD hom?.txt /mydir/

<dest> is an absolute path, or a relative path relative to WORKDIR.

九、COPY​

The syntax is the same as ADD, which copies a copy file.

The only difference between the COPY command and the ADD command is whether or not it supports fetching resources from a remote URL. COPY can only read resources from the host where the docker build is executed and copy them to the image. The ADD command also supports reading resources from a remote server via a URL and copying them to the image.

The ADD command is better at reading and unzipping local tar files.

X. ENTRYPOINT​

ENTRYPOINT, like CMD, specifies the container launcher and its parameters, but it is not overridden by the command specified in the command line argument of docker run. If you want to override it, you need to specify it with docker run --entrypoint.

It comes in 2 formats.

ENTRYPOINT ["executable", "param1", "param2"]
ENTRYPOINT command param1 param2

When ENTRYPOINT is specified, the content of the CMD is passed as an argument to the ENTRYPOINT directive, which, when actually executed, will read:

<ENTRYPOINT> <CMD>

十一、VOLUME​

Creates a mounted data volume with the specified name.

VOLUME ["/var/log/"]
VOLUME /var/log

Its main function is to

  • Avoid important data, which is lost due to container restart
  • Avoid the container to keep getting bigger

XII. ARG​

Defines variables that serve the same purpose as ENV, except that ARG variables are not persisted to the built image as ENV variables are.

ARG <name>[=<default value>]

Docker has a set of predefined ARG variables that you can use in the absence of a corresponding command in the Dockerfile.

  • HTTP_PROXY
  • http_proxy
  • HTTPS_PROXY
  • https_proxy
  • FTP_PROXY
  • ftp_proxy
  • NO_PROXY
  • no_proxy

To use these, pass them on the command line using the -build-arg flag, e.g.

 docker build --build-arg HTTPS_PROXY=https://my-proxy.example.com .

十三、ONBUILD​

Add a trigger command to the image to be executed later when the image is used as the base for another build. That is, when another dockerfile has been FROM this image.

ONBUILD ADD . /app/src
ONBUILD RUN /usr/local/bin/python-build --dir /app/src

十四、STOPSIGNAL​

Sets the system call signal that will be sent to the container exit. The signal can be a valid unsigned number matching a location in the kernel system call table, e.g. 9, or a signal name in the format SIGNAME, e.g. SIGKILL.

STOPSIGNAL signal

The default stop-signal is SIGTERM, which will be sent to the process with PID 1 in the container when docker stop, you can set the signal you need through --stop-signal, the main purpose is to let the application in the container can handle some things after receiving the signal, to achieve a smooth exit of the container. If nothing is done, the container will be forced to exit after a certain period of time, which will cause a forced interruption of the business, the default time is 10s.

十五、HEALTHCHECK​

Used to specify a program or command to monitor the running status of the docker container service. This HEALTHCHECK command has two forms.

  • HEALTHCHECK [OPTIONS] CMD command (checks container health by running the command inside the container)
  • HEALTHCHECK NONE (disables any health checks inherited from the base image)

十六、SHELL​

Override the default shell of the form shell used for commands. the default shell on Linux is ["/bin/sh", "-c"] and on Windows it is ["cmd", "/S", "/C"]

SHELL ["executable", "parameters"]

The SHELL command is particularly useful on Windows, which has two common and distinct native shells: cmd and powershell, as well as available alternate shells, including sh. The SHELL command can appear multiple times. Each SHELL command overrides all previous SHELL commands and affects all subsequent commands.

xvii. WORKDIR​

The working directory, if WORKDIR does not exist, will be created even if it is not used in subsequent Dockerfile directives.

A new layer is created with each RUN command during the docker build image build process. Only the directories created by WORKDIR will always exist.

Multiple WORKDIRs can be set, and if a relative path is provided, it will be relative to the path of the previous WORKDIR command. For example.

WORKDIR /a
WORKDIR b
WORKDIR c
RUN pwd

The final output of the pwd command is /a/b/c.

This WORKDIR command can resolve previous use of ENV, e.g.

ENV DIRPATH=/path
WORKDIR $DIRPATH/$DIRNAME
RUN pwd

The final output of the pwd command is /path/$DIRNAME.

xviii. USER​

Set the user name (or UID) and optionally the user group (or GID)

USER <user>[:<group>]
USER <UID>[:<GID>]

Dockerfile文件全面详解 - 青火的文章 - 知乎 https://zhuanlan.zhihu.com/p/387855002